///////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2009 Summit Contributors.  
// See: http://code.google.com/p/tyemill/wiki/SummitContributors
//
// The name and logo of Summit are trademarks of TYEMILL, LLC - All Rights 
// Reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a 
// copy of this software and associated documentation files (the "Software"), 
// to deal in the Software without restriction, including without 
// limitation the rights to use, copy, modify, merge, publish, distribute, 
// sublicense, and/or sell copies of the Software, and to permit persons to 
// whom the Software is furnished to do so, subject to the following 
// conditions:
//
// The above copyright notice and this permission notice shall be included 
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.
///////////////////////////////////////////////////////////////////////////////

package summit.basecamp.wrappers
{
import summit.basecamp.constants.BasecampResource;
import summit.basecamp.constants.CommentableType;
import summit.basecamp.helpers.MessageHelper;
import summit.data.AccountToken;
import summit.net.BasecampLoader;

/**
 * Wrapper for Basecamp message operations.
 */
public class MessageWrapper extends AbstractWrapper implements
IStandardWrapper, ICommentableWrapper, IListableWrapper
{
    /** Constructor.
	 * @param token The <code>AccountToken</code> that is to be used in
	 * identifying the Basecamp account to which API calls are made.
	 * @param loader The <code>BasecampLoader</code> that is to be used 
	 * with all requested operations.
	 */
	 
	public function MessageWrapper(token:AccountToken = null, 
	loader:BasecampLoader = null)
	{
		super(BasecampResource.MESSAGE, token, loader);
	}
	
	/** Returns the <code>CommentableType.POST</code>. **/
	public function get commentableType():String
	{
		return CommentableType.POST;
	}
	
	/**
	 * Creates a new message.
	 * 
	 * <p>Typically, the XML provided is based on the template returned from
	 * a call to <code>prepare</code>.</p>
	 * 
	 * <p><code>title</code> is a required field in the XML, as is the 
	 * <code>project-id</code> that identifies the project associated 
	 * with the message. </p>
	 * 
	 * <p>Optionally, the message can contain flags for notifing team members 
	 * on the posting of this message.</p>
	 * 
	 * <p>Also, the message can contain references to attachments that 
	 * were added in previous uses of the <code>AttachmentHelper</code>.</p>
	 * 
	 * @param content Represents a category.
	 */
	public function create(content:XML):void
	{
		loader.load(MessageHelper.create(content));
	}
	
	/**
	 * Deletes a message.
	 *
	 * <p>The message and all associated comments are deleted.</p>
	 * 
	 * @param id The id of the message to be deleted.
	 */
	public function destroy(id:String):void
	{
		loader.load(MessageHelper.destroy(id));
	}
	
	/**
	 * Gets an existing message from the Basecamp store.
	 * 
	 * <p>The XML returned is pre-filled with the existing values of 
	 * the identified message, and is ready to be resubmitted via the 
	 * <code>update</code> function.</p>
	 * 
	 * @param id The id of the message to be retrieved.
	 * @param projectId The id of the project associated with the message.
	 */ 
	public function edit(id:String, projectId:String):void
	{
		loader.load(MessageHelper.edit(id));
	}
	
	/**
	 * Gets the last 25 messages posted to a project.
	 * 
	 * @param projectId The id of the project from which messages are 
	 * read.
	 */
	public function list(projectId:String):void
	{
		loader.load(MessageHelper.list(projectId));
	}
	
	/**
	 * Reads a list of messages scoped by category.
	 * 
	 * <p>Gets the last 25 messages posted to a project, grouped with 
	 * the specified category.</p>
	 * 
	 * <p>If <code>archived</code> is set to <code>true</code>, all messages
	 * are retrieved, however, they are not full messages. Instead, all 
	 * messages are in abbreviated format.</p>
	 * 
	 * @param projectId The id of the project from which messages are 
	 * read.
	 * @param categoryId The id of the category used to scope the list.
	 * @param archived Set to <code>true</code> if all message should be
	 * listed.
	 * 
	 */
	public function listByCategory(projectId:String, categoryId:String, 
	archived:Boolean = false):void
	{
		loader.load(MessageHelper.list(projectId, categoryId, archived));
	}
	
	/**
	 * Retrieves a template for creating a new message.
	 * 
	 * <p>The template retrieved is used with <code>create</code> to 
	 * submit a new message.</p>
	 * 
	 * @param projectId The id of the project that is to be associated 
	 * with the message when submitted via a call to <code>create</code>.
	 */ 
	public function prepare(projectId:String):void
	{
		loader.load(MessageHelper.prepare(projectId));
	}
	
	/**
	 * Gets a single message.
	 * 
	 * @param id The id of the message to be read.
	 * @param projectId The id of the project that is associated with
	 * the message.
	 */
	public function read(id:String, projectId:String):void
	{
		loader.load(MessageHelper.read(id));
	}
	
	/**
	 * Updates an existing message.
	 *
	 * <p>The call to <code>update</code> is typically made with the content
	 * from the call to <code>edit</code>.</p>
	 *  
	 * <p>Optionally, the XML can contain flags for notifying team members 
	 * on the changes to the message.
	 * 
	 * <p>Additionally, attachments can be associated with the message,
	 * however, the attachments must have been uploaded prior 
	 * to association.</p>
	 *  
	 * @param content The XML content of the new message.
	 */ 
	public function update(content:XML):void
	{
		loader.load(MessageHelper.update(content));	
	}
}
}
//////////////////////////////////////////////////////// gmarius@tyemill.com //